Copyright: "Personal Helper Help FIle "


Personal Helper

Personal Helper is a utility for VB Pro Developers that allows you to create help topics for VB projects, using one of three different methods. You enter the text for each topic using a built-in editor which translates most common formatting requirements into Help Compiler Commands.  When done, Help Compile the ready-made Help Source, merge a prepared .HBA file into your project, and call Get_Help from your form_load procedure.

Introduction to Help Files

Help Files are created from a process very similar to that used in creating programs. They have their own compiler (HC31.EXE), a  make  file (.HPJ), and one or more source  files ( RTF).  Each topic is assigned a Context ID (a number), which you can then use to look up a specific topic to display. Creating proper source files using footnotes and strange formatting commands has made help file creation difficult. In addition, you needed a word processor which created files in RTF format, and you had to create the makefile essentially by hand.

How Personal Helper Helps

Personal Helper assists you by making the creation of topics as painless as possible, and then allows you to create formatting commands without having a RTF word-processor. In fact, you don't even need to know what the commands are; you use a button-bar to click on the formatting that you want to implement (Bold, Italic, Center, Import Bitmap, Change Color, Change Font,etc.). You can also add popups and jumps to your topic, and optionally display these views in a secondary window. Or, if you own Word and prefer to use it for your text editor, Personal Helper lets you automate Jumps and Popups by pressing on the Jump button to get a list of valid topics.

 You can view your work directly in the Help System at each step. You can also create the Windows Help File and the VB Subroutine File while remaining in the environment .

Creating Projects

Before you can enter topics, you must create a project. This is usually, but not necessarily,  the name of the application you are creating the help file for. There are certain default attributes for the project, such as the font style and size you want to use. While your database can have many  projects, you can only work on one project at a time.

Creating Topics

Once you have chosen the project you want to work on, you will need to create the Topics that you want to enter. Topics have a Mnemonic, which is used internally to identify the item, a Description that appears to the viewer, keywords for which this topic will show up in a keyword  search, and other attributes. You can create topics in one of three ways: 1) Import a project from  a .MAK file, allowing the program to create a topic for each valid control, 2) Create individual topics manually, or 3) going into Viewer mode and pressing Shift-F1 when the cursor detects a VB control.

Entering Text

After creating and choosing a topic, you can enter the topic's text. This is discussion that will appear when the user chooses help for this topic. You can now choose between using Word for text entry,or using the built-in Text Editor.

•	Using Microsoft Word for entering text.

If you are using Word, you can add popups and jumps to other topics, by pressing the Jump button on the buttonbar, or pressing Alt-J. Write your text and save it, then exit Word to go back to the Personal Helper Maintenance Form. NOTE: you may need version 3.10.505 of the Help Compiler if you use Microsoft Word v 6.0a. If so rename the version you download from Microsoft, make certain you rename it to HC31.EXE. If you dont use bitmaps, you may not need to do this.

•	Using the Text Editor for entering text.

If you are using the Text Editor, you will have a buttonbar that enables you to enter the cryptic RTF commands for most basic formatting requests (Bold, Italic, Center, Fontsize, Color, etc;) You will also be able to add popups and jumps to other topics, all without having to remember the .RTF conventions.

Viewing the Help Text

While in the Text Editing mode, you can view how the particular topic will look by choosing the View button. This will fire up the Help System, and show you the current topic directly in Help, so you'll know exactly how it will look. After closing the helpfile, it's easy to go back and make changes without ever having to leave the editing screen.

Audit the Helpfile

You might want to audit your help file, before creating, to ensure that all topics that you are jumping to or popping up (if you use this capability) are actually being created. If you jump to a topic, but then neglect to put in text for that topic, you will get a TOPIC NOT FOUND  message when you run help and click on that jump.

Making the Helpfile

You can also create the entire helpfile, either in the Text Edit mode or in the Maintenance mode. At this point, all topics for which there is text will be created and linked together. The program will also produce a text file for inclusion in your .MAK file, (.HBA extension). This file should be merged into an existing module. It contains a subroutine called Get_Help() which you will need to call from your main form's form_load method. This subroutine maps the .HLP file to the application, and assigns id numbers to all the control topics. Re-Compile your project, and help is now integrated into your application.

NOTE: When VB assigns a Help context id to a form or control, it actually loads that form. This can lead to strange error messages when you go to load your project, if certain events (such as data being loaded, etc.) that normally occurs BEFORE the form or control is activated has not yet happened. If so, remove the .HELPCONTEXID lines and move them into this form's LOAD method. eg, if one of the lines in Get_Help is frmMyMDIChild.Helpcontextid=7, but  you don't want the MDI children to load yet because some other action has to take place, move this line into the frmMyMDIChild.Form_Load method. It will now not be called UNTIL the form is loaded.

Creating a Manual

If you have Word, you can now create a hard-copy manual of your helpfile by pressing the Manual button under project. This will take each topic, and insert it into a file. It will have all topic and index flags prepared for you making it easy to add a table of contents and index, if you wish. NOTE: As of this writing, there is a problem with suppressing footnotes/endnotes. The checkbox is either unactivated, or doesnt suppress endotes or footnotes. Because you cant just go to the endnotes window, hit Ctrl-A and Delete to remove all the footnotes (Im not sure why, but this isnt allowed), you may have to delete them by hand.

Gettting Started

First time through, you are asked to read this helpfile, at least this topic; When you close this file, a database will be created, and the first project will automatically be created, called PROJ_1 unless you decide to change it. From there, you will be in Maintenance mode. You can press F1 on each form, and receive information specific to the form or control.

NOTE: This is not freeware; if you use this application, you are required to register.Please send $35 to:

 FAR, Inc.

POB 202

Oak Forest, IL 60452


Viewer Help

Viewer is invoked by pressing Shift-F1. Once invoked the following four buttons are active:

Edit may or may not be active. If the last control that the mouse pointer was on was a valid VB  control, this button will allow you to review/create an edit help context for the item. It will place you in the edit form. If the last control for the mouse pointer wasn't a valid VB control, this button will be disabled.

Maintenance will take you to the maintenance form.

Continue will place the viewer back in "spy" mode, at the bottom of the screen.

End will end the program.


Maintenance Help

This form is divided into parts, Projects and Topics. After adding or choosing the Project you want to work on, you need to choose a Topic. You will then be able to change topic attributes, such as description, keywords, etc., or you will be able to edit the text discussion for the item. As a rule, double click on the cell you want to change or work on. Any associated input boxes, lists, etc., should show up then.

Projects

A Project has a project name, a default font, fontsize, and can have an optional Icon associated with it (otherwise, the help icon is used). If you choose to import an entire project, it will also have a source project file associated with it. To change an item, double click on the cell. Depending on the column, a dialog box or input box may appear.

The buttons on the bottom of the frame are:

New to add a new project. This is assigned PROJ_# (the next project number) automatically. You can change it to the name of the project you are working on, etc.

Import  to import all topics for a given project. You will be asked for a project .MAK file, and then Personal Helper will read the .MAK, create a APP!MAIN topic as the default help topic name for the application, and then create a topic for each IDENTIFIED CONTROL TYPE found in the project. IDENTIFIED CONTROL TYPES are the CONTROL MNEMONICS for which you might want to create help topics. IDENTIFIED CONTROL TYPES are assigned based upon the values in a file called "CONTROLS.LST" in the Personal Helper Default Directory. You can add or delete controls to this ascii text file, just be certain they are the exact control names associated with the control.

As a word of warning, NOT all controls are found by Windows. For example, if you position the cursor over a LABEL control, Windows doesn't even know there's anything there; it just sees the frame or form that the label is on. These are VB "Graphical Controls", which are a VB construct, and for which Help may not work. In general, don't worry about it. Just let the Importer suck in the controls it can find. You won't produce help for any topics for which you don't enter a text discussion.

Audit is an optional context auditor that lets you check that you aren't jumping from one help topic to a topic for which there is no text. This is important because Personal Helper won't attempt to create a topic file for every control in your project, only for those for which there is text. If you jump to a topic for which there is no text, a "Topic Not Found" error will occur in your helpfile. If you use jumps or popups in your help system (many developers find they don't even need to), you might want to run the auditor before creating the help file.

Update will update changes you have made to the Project identifiers, etc. Updates happen automatically when you change rows. It is necessary to UPDATE before creating the help file if you want your changes to take effect.

Make actually makes the help file and a VB .HBA file for you to include in your project. You only use this control AFTER you have entered the text description for the topics.

Make produces intermediate files, but also 2 files of interest to you: a .HLP  help file, and a .HBA VB merge file.

The .HLP file is created by: 1) Creating a .HPJ help compiler make file, 2) creating a .RTF help text file for each topic for which there is text, and 3) calling the HC31.EXE help compiler. For this reason, HC31.EXE must be in the Path  in order for the help file to be produced automatically. The resulting file will be called projname.HLP.

The .HBA file (projname.HBA) will be produced in the default directory of the imported project. This file contains a single subroutine (GET_HELP) which contains the name of the Help file, and maps individual control help id's to their appropriate identifier in the help file. You import this file into you project, Merging it into a Module File. You then call Get_Help in the Form_Load method of your main form. Re-Compile your VB project, and the help system will now be fully functional.

NOTE:  VB loads ALL forms in order to add the help context ID to any control or the form itself. Sometimes, you may not want this to happen, like when you want to get data before you load a child file. If you find this to be the case, move the .HelpContextID= lines from the Get_Help sub to the Form_Load method of the form in question. (See the Personal Helper topic below for further information)	Delete will remove a project from the help system. This will erase all text you wrote for the project, so use this option with discretion. If you want to create a new help file for a project, you don't need to delete the old one; just add it again with a different project name. It will still work.

Manual is an option for those who have WORD. You can create a copy of the help file texts in Manual form by pressing this button. It will insert each topic in sequential order into a file named projname.DOC. You can then edit this file, add a Table of Contents and Index, etc.

NOTE: As of this writing, the "Suppress Endnotes" checkbox is never activated, even when there are endnotes/footnotes in the document. Consequently, you may need to manually delete footnotes. Due to a "design decision" in WORD, you can't  Ctrl-A /Delete all footnotes in the footnote window; you need to delete them individually.

End will end Personal Helper.

TOPICS

Topic Columns

Topics have attributes that besides their text. They have a context id (mnemonic) which identifies them internally (e.g., "APP!MAIN" is the context number 0, the main help screen for the file), a description associated with them that is shown to the user ("Personal Help"), keywords by which the user is able to look them up ("MAIN", "APPLICATION"), and a sequence in which they can be scrolled within the help system.They can also have an optional bitmap associated with them.

Topic is the context id which is associated with the topic. It is convenient shorthand for referring to the topic independent of its longhand description. In Personal Helper, these contexts are usually the name of the control. NOTE: You should probably NOT change the name of these ids if you are using them with a VB project. They map to the name of the control for which you are creating help. If you change them, VB will not know what they are help for. If you double click on this cell, you will end up in edit mode for the text.

Description is the heading that the user will see for the topic on the help screen and in the keywords description. Change this (40 chars or less) to be whatever you want the heading to be. To change, double click on the cell and an input box will appear. (If the field turns light blue, you're in the TrueGrid edit mode for the field; You can also enter the description this way, but you'll have to manually delete the old characters, etc.).

Keywords are the keys by which a user will be able to find the description from the Search command in help. Double Click on this field, and you will get a listbox of all currently valid keywords. Change these to reflect what you want to add or delete, and then return to the maintenance screen.

Bitmap is optional. If you want to associate a .BMP file with the topic, you can double click on this cell. A dialog box asking for the .BMP name will appear. After choosing the appropriate bitmap, whenever the bitmap will appear in the heading for the topic, as well as whenever you choose to jump to it from another topic. NOTE: As this is written, we have discovered some incompatibilities of the .BMP commands when importing our files into MS Word v 6.0a. If you are concerned about compaitiblity, you may not want to include bitmaps in your project.

Sequence is the sequence order in which you want the topics to appear. The original sequence number determined for imported projects is to use the sequence of the .MAK file; first the form, then each control on each form, then the next form, etc. If this is not the order in which you want your users to sequence through help, you can change it. DRAG AND DROP is implemented for changing sequences. See the hand-on-document icon near the bottom of the form ? Drag a topic down to it by Pressing the left mouse button, leaving it depressed, move it t the Doc icon,  and release the mouse. You should see the context ID for this topic in the icon; You've captured it. Now, move to the spot where you want to insert the topic. Use DRAG AND DROP again, only in reverse, to insert the topic. (Press on the icon, move to the row where you want to insert, and then let go). The topic should now be inserted at that point.  NOTE: We recommend that you not change APP!MAIN from being the first context. Any other context can be moved anywhere you like.

Text will tell you whether or not there is text for this item. If there is, it will say "TEXT"; if not, it will say "NONE". If you double click on this column, you will be transferred into Edit mode.

TOPIC BUTTONS

New will create a new topic at the end of the table. You can use this if you want to create topics that aren't associated with VB project controls, and you want to jump to them as further discussion items.

Update will save any changes you have made to topic attributes for the topic you are working on; changes are automatically saved when you move from one row to the next.

Edit transfers you to the topic text edit form. This is where you will edit the text for the item.

Print prints the data summary for the project topics; NOTE! This uses Crystal v3.0, which is not a real swell product as of this writing. For this reason, we've included the Crystal .DLL's and .VBX's. If you are a heavy user of Crystal, and experience problems w/your apps, you may want to copy CRPE.DLL over to your Personal Helper subdirectory and re-install version 2.0

Viewer is an entirely different way of using the program. You can choose to put Personal Helper into "Spy" mode, using Spyworks tools, and it will shrink into the lower left-hand portion of your screen.  When in viewer mode. you can choose to either edit your application in VB, or create an executable and run it. Whenever your cursor (mouse pointer) passes over a valid VB control (form, listbox, commandbutton, optionbutton, etc.), the cursor will change to a set of eyes and the name of the control will appear in the body of the viewer. If this is the control for which you want to create text, press Shift-F1. The Viewer form will now center itself on the screen. Switch to this form, and you will see buttons that allow you to Edit the text for the item, Go back to the Maintenance Form, put the viewer back into viewer mode, or end the program. When done editing text, you can choose Continue to put the viewer back into "spy" mode and continue working on your project.


About...

Personal Helper is a utility for VB Developers. Please read the following help topic if you  have not already done so.

Personal Helper


Audit Help

Auditing reduces the chance of "Help Context Not Found" errors in your helpfile. The auditor polls your jumps and popups to ensure that they are all to topics that have text. This is important because Personal Helper only creates Help topics for those topics that have text.

If you use jumps or popups in your help topics, auditing ensures that you will not have problems.

You can double click on the error item to immediately go into editor mode and add text for the item.


Editor Help

Topic Editor

The topic editor allows you to create help topics without having to know RTF commands. Etner your text, and use the button bar for formatting.

Bold Button, when down, will place all text in bold. When up, text will be normal.

Italic Button, when down, will place all text in italics. When up, text will be normal

Tab Button  will insert a tab

Para Button will insert a new line

Center Button, when down, will center text on the form. When up, text will be normal.

Picture Button will insert a bitmap into the help file

Cut Button will cut any selected text (TEXT ONLY!) to the clipboard.

Copy Button will copy any selected text (TEXT ONLY!) to the clipboard.

Paste Button will paste any text in the clipboard to the selected area

View Button enables you to get a quick view of the topic in the Help System.

Make Button enables you to create the .HLP file and the .HBA file for the entire project.

Save Button allows you to save your work

Fontsize SpinButton allows you to increase/decrease the font size for the text.

Color Button enables you to change text color (black,blue,red only colors supported)

You can change the topic you want to create text for by changing the active choice in the topic combo box. NOTE: remember to save your work before you change topics.

TOPIC is for creating jumps or popups to other topics from within the active topic.

First, make certain that the topic to which you wish to jump is the selected topic in the jump topic combobox.

Second, choose either Popup  (single underline) or Jump  (Double underline).

If you choose a jump topic, you will be asked if you want to display it in a secondary window. If you choose to do so, the current topic will remain on the screen in the original window, and the jump topic will appear in an overlaid screen on top of it. If you don't use a secondary window, the active help topic will change to the jump topic. You can always use History to return, however.

Choose OK to return with save, Cancel to return without saving any changes. If you no longer want a help topic printed, erase all text and save it before returning.


Keywords Help

Keywords are words that will be used to find a topic by Search keys in help.

Add will add a keyword to the list. Add only one keyword at a time.

Delete will remove the hightlighted keyword from the list.

Return will return to the Maintenance form.

Note: The Keywords column only shows the beginning of your keyword list; to see the whole list, you'll need to double click on the cell you want to see.